Skip to main content

Call Fabric

Call Fabric is the embodiment of SignalWire's vision for Programmable Unified Communications. It is effectively a new paradigm in communications, designed to streamline usage and development across all communication types.

Check out our What is Call Fabric? guide to learn more, and make sure to read our CEO's blog to see how it the next evolution from FreeSWITCH!

The following section details the mechanisms available in the SignalWire browser SDK (@signalwire/js) to take advantage of the Call Fabric architecture.

This product is in alpha state

Call Fabric additions to SignalWire's Browser SDK are in Alpha State, and should not be used in production.

However, please feel free to get in touch with our support team with concerns, bugs or, feature requests.

Installation​

Call Fabric is available in the SignalWire Browser SDK (@signalwire/js) versions 3.27.0 and later.

If your project uses a package manager, the Browser SDK can be installed like so:

npm install @signalwire/js

It is also available through our CDN and can be included directly into the <head> section of your webpage.

<script src="https://cdn.signalwire.com/@signalwire/js"></script>

Once installed, you can take advantage of the new capabilities that Call Fabric enables by instantiating a SignalWire Client, like so:

<script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
<script>
  async function main() {
    const client = await SignalWire.SignalWire({
      token: "<TOKEN>",
    });
  }
</script>

The access token is received after the Call Fabric subscriber completes the OAuth2 flow and successfully logs in. Learn more at the Authentication section further below.

Concepts​

Resources​

Resources are the primary entities for communication within SignalWire. Resources include: Subscribers SWML Scripts, SignalWire AI Agents, Video-Rooms, SIP Endpoints, etc.

Subscribers​

Subscribers represent the end-users within SignalWire. They are the endpoints of communication, capable of receiving or initiating calls, messages, and other forms of interaction.

SignalWire allows subscribers to switch from one type of communication to another. For example, switching from a phone call into a video-room to a web-based video call.

You can create Subscribers and Resources in the Resource section of your SignalWire Dashboard, or with a HTTP POST request:

curl --location --request POST 'https://spacename.signalwire.com/api/fabric/subscribers' \
--user "project_id:api key" \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[the subscriber email]",
    "password": "[the subscriber password]"
}'

Addresses​

Each resource and subscriber is uniquely identified by an addresses which can be called, sent messages to, or interacted with in some other way.

The address is composed of two parts: "/context/name"

  • Context: A identifier that indicates in which context the resource is located.
  • Name: The name is the unique identifier for the resource.

For example, the address for a Subscribers resource named Alice in the public context would be /public/Alice.

Authentication​

OAuth2 based authentication for Subscribers​

When you create a Subscriber, you assign them a username (email) and a password. These credentials can be used authenticate the subscriber using the standard OAuth2 flow with PKCE. For OAuth2, you can use tools like odic-client-ts or react-native-app-auth.

You can also use this node.js script from SignalWire Community to get a token for a subscriber.

import { UserManager, WebStorageStateStore } from "oidc-client-ts";

const config = {
  authority: "x", // dummy authority
  metadata: {
    issuer: "https://id.fabric.signalwire.com/",
    authorization_endpoint: "https://id.fabric.signalwire.com/login/oauth/authorize",
    token_endpoint: "https://id.fabric.signalwire.com/oauth/token",
  },
  client_id: "<Your_Fabric_Client_id>",
  redirect_uri: "https://redirect_uri",
  response_type: "code",
  userStore: new WebStorageStateStore({ store: window.localStorage }),
};

const userManager = new UserManager(config);

await userManager.signinRedirect();

A complete example is presented below. Assuming that this page is npx served at the address http://localhost:3000, this script takes the subscriber through the OAuth2 login flow, and uses the access token received to fetch the subscriber's registration details from SignalWire.

index.html
<html>
  <head>
    <style>
      .loading > button { display: none }
      .loading::after { content: "Loading..." }
    </style>
  </head>

  <body>
    <div id="container" class="loading">
      <button onclick="userManager.signinRedirect()">Log In</button>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/oidc-client-ts@3.0.1/dist/browser/oidc-client-ts.min.js"></script>
    <script src="https://cdn.signalwire.com/@signalwire/js"></script>
    <script>
      const container = document.getElementById("container");

      const config = {
        authority: "x", // dummy authority
        metadata: {
          issuer: "https://id.fabric.signalwire.com/",
          authorization_endpoint: "https://id.fabric.signalwire.com/login/oauth/authorize",
          token_endpoint: "https://id.fabric.signalwire.com/oauth/token",
        },
        client_id: "<Your_Fabric_Client_id>",
        redirect_uri: "http://localhost:3000", // assuming this page is being served at port 3000 of localhost
        response_type: "code",
        userStore: new oidc.WebStorageStateStore({ store: window.localStorage }),
      };

      const userManager = new oidc.UserManager(config);

      async function checkForRedirect() {
        try {
          const user = await userManager.signinRedirectCallback();
          if (user) {
            // the oauth flow completed successfully, we can now use Call Fabric features using the access token.
            await getSubscriberInfo(user.access_token);
          }
        } catch (e) {
          // signinRedirectCallback failed; login flow hasn't been started yet. We'll show the Login button.
          container.classList.remove("loading");
        }
      }

      async function getSubscriberInfo(token) {
        const client = await SignalWire.SignalWire({ token });
        const subInfo = await client.getSubscriberInfo();

        container.classList.remove("loading");
        container.innerText = `Hello, ${subInfo.first_name}`;
      }

      // We want to check if the user was redirected here from the subscriber login flow,
      // or if the came here directly from the browser. If the user came directly from the 
      // browser, we show a Login button. If they were redirected here, we allow oidc-client-ts
      // to finish the flow and get the access token.
      checkForRedirect();
    </script>
  </body>
</html>